/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements. See the NOTICE file distributed with this
 * work for additional information regarding copyright ownership. The ASF
 * licenses this file to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package org.apache.mina.common;

import java.net.SocketAddress;

/**
 * Connects to endpoint, communicates with the server, and fires events to
 * {@link IoHandler}s.
 * <p>
 * Please refer to <a href=
 * "../../../../../xref-examples/org/apache/mina/examples/netcat/Main.html"
 * >NetCat</a> example.
 * <p>
 * You should connect to the desired socket address to start communication, and
 * then events for incoming connections will be sent to the specified default
 * {@link IoHandler}.
 * <p>
 * Threads connect to endpoint start automatically when
 * {@link #connect(SocketAddress, IoHandler)} is invoked, and stop when all
 * connection attempts are finished.
 * 
 * 连接到端点，与服务端通讯，并触发事件到IoHandler。
 * 你应该连接到被请求的socket地址来开始通讯，进来的连接的事件将会被发送到指定的IoHandler。
 * 当connect(SocketAddress,IoHandler)被调用的时候，线程将会自动连接到端点。当所有的连接尝试完成时，线程将会停止。
 */
public interface IoConnector extends IoService {
    /**
     * Connects to the specified <code>address</code>. If communication starts
     * successfully, events are fired to the specified <code>handler</code>.
     * 
     * 连接到指定的address。如果通讯成功开始，事件将会触发到指定的handler。
     * 
     * @return {@link ConnectFuture} 连接尝试的结果。
     * 
     */
    ConnectFuture connect(SocketAddress address, IoHandler handler);

    /**
     * Connects to the specified <code>address</code>. If communication starts
     * successfully, events are fired to the specified <code>handler</code>.
     * 
     * 连接到指定的address。如果通讯成功开始，事件将会触发到指定的handler。
     * 
     * @param config
     *            the configuration
     * @return {@link ConnectFuture} 连接尝试的结果。
     */
    ConnectFuture connect(SocketAddress address, IoHandler handler,
            IoServiceConfig config);

    /**
     * 连接到指定的地址。如果通讯开始开始，事件将会分配给指定的处理器。
     * 
     * @param localAddress
     *            channel绑定的本地地址
     * @return {@link ConnectFuture} 连接尝试的结果。
     */
    ConnectFuture connect(SocketAddress address, SocketAddress localAddress,
            IoHandler handler);

    /**
     * Connects to the specified <code>address</code>. If communication starts
     * successfully, events are fired to the specified <code>handler</code>.
     * 
     * 连接到指定的address。如果通讯成功开始，事件将会解决到指定的handler。
     * 
     * @param config
     *            配置
     * @return {@link ConnectFuture} 连接尝试的结果。
     */
    ConnectFuture connect(SocketAddress address, SocketAddress localAddress,
            IoHandler handler, IoServiceConfig config);
}